Is a Single Embedding Enough? Learning Node Representations that Capture Multiple Social Contexts
===============================

This is the implementation accompanying the WWW 2019 paper,
[_Is a Single Embedding Enough? Learning Node Representations that
Capture Multiple Social Contexts_](https://ai.google/research/pubs/pub47956).
The code also allows to create persona graphs to obtain overlapping clusters as
defined in the KDD 2017 paper [_Ego-splitting Framework: from Non-Overlapping 
to Overlapping Clusters_](https://ai.google/research/pubs/pub46238).

Example Usage:
--------------
First, create a fresh virtual environment and install the requirements.

    # From google-research/
    virtualenv -p python3 .
    source ./bin/activate

    python3 -m pip install -r graph_embedding/persona/requirements.txt

Both Splitter and the Persona Decomposition operate over edge lists (which can
be exported by [NetworkX](https://networkx.github.io/).

Splitter
-------

You can create a Splitter embedding like the following.

    python3 -m graph_embedding.persona.splitter \
      --input_graph=GRAPH.edgelist \
      --output_persona_embedding=GRAPH_persona.embedding \
      --output_embedding_prior=GRAPH_deepwalk.embedding \
      --output_persona_graph_mapping=GRAPH_persona_map.txt

Persona Decomposition
---------------------

You can also run the person decomposition independently, like so:

    # From google-research/
    python3 -m graph_embedding.persona.persona --input_graph=${graph} \
       --output_clustering=${clustering_output}

Note on using the embeddings
---------------------
Our method outputs multiple embeddings per node, so downstream learning tasks
must be able to handle multiple embeddings. In our experiments with
link prediction we use the following simple method: for a pair u and v of nodes
in the original graph, we predict the edge u,v with a score given by the
maximum of the *cosine* similarity of any pair of one splitter embedding of u,
and one splitter embedding of v.

Citing
------
If you find _Persona Embedding_ useful in your research, we ask that you cite
the following paper:

> Epasto, A., Perozzi, B., (2019).
> Is a Single Embedding Enough? Learning Node Representations that Capture
Multiple Social Contexts.
> In _The Web Conference_.

    @inproceedings{epasto2019learning,
     author={Epasto, Alessandro and Perozzi, Bryan}
     title={Is a Single Embedding Enough? Learning Node Representations that
     Capture Multiple Social Contexts},
     booktitle = {The Web Conference},
     year = {2019},
    }

Notes
------

Splitter currently assumes that the nodes are consecutive integer ids starting
at 0, (a less strict restriction is actually enforced -- any node ids which
don't collide with the ids generated by the persona graph are probably fine).

Contact Us
----------
For questions or comments about the implementation, please contact
<aepasto@google.com> and <bperozzi@acm.org>.
